<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tcl_CreateAlias manual page - Tcl Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> CrtAlias</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="CrtAlias.htm#M2" NAME="L109">NAME</A>
<DL><DD>Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand &mdash; manage multiple Tcl interpreters, aliases and hidden commands</DD></DL>
<DD><A HREF="CrtAlias.htm#M3" NAME="L110">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tcl.h&gt;</B>
<DD>int
<DD><B>Tcl_IsSafe</B>(<I>interp</I>)
<DD>int
<DD><B>Tcl_MakeSafe</B>(<I>interp</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_CreateChild</B>(<I>interp, name, isSafe</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_CreateSlave</B>(<I>interp, name, isSafe</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_GetChild</B>(<I>interp, name</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_GetSlave</B>(<I>interp, name</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_GetParent</B>(<I>interp</I>)
<DD>Tcl_Interp *
<DD><B>Tcl_GetMaster</B>(<I>interp</I>)
<DD>int
<DD><B>Tcl_GetInterpPath</B>(<I>interp, childInterp</I>)
<DD>int
<DD><B>Tcl_CreateAlias</B>(<I>childInterp, childCmd, targetInterp, targetCmd,
<DD>argc, argv</I>)
<DD>int
<DD><B>Tcl_CreateAliasObj</B>(<I>childInterp, childCmd, targetInterp, targetCmd,
<DD>objc, objv</I>)
<DD>int
<DD><B>Tcl_GetAlias</B>(<I>interp, childCmd, targetInterpPtr, targetCmdPtr,
<DD>argcPtr, argvPtr</I>)
<DD>int
<DD><B>Tcl_GetAliasObj</B>(<I>interp, childCmd, targetInterpPtr, targetCmdPtr,
<DD>objcPtr, objvPtr</I>)
<DD>int
<DD><B>Tcl_ExposeCommand</B>(<I>interp, hiddenCmdName, cmdName</I>)
<DD>int
<DD><B>Tcl_HideCommand</B>(<I>interp, cmdName, hiddenCmdName</I>)
</DL>
<DD><A HREF="CrtAlias.htm#M4" NAME="L111">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="CrtAlias.htm#M5" NAME="L112">DESCRIPTION</A>
<DD><A HREF="CrtAlias.htm#M6" NAME="L113">SEE ALSO</A>
<DD><A HREF="CrtAlias.htm#M7" NAME="L114">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand &mdash; manage multiple Tcl interpreters, aliases and hidden commands
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
int<BR>
<B>Tcl_IsSafe</B>(<I>interp</I>)<BR>
int<BR>
<B>Tcl_MakeSafe</B>(<I>interp</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_CreateChild</B>(<I>interp, name, isSafe</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_CreateSlave</B>(<I>interp, name, isSafe</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_GetChild</B>(<I>interp, name</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_GetSlave</B>(<I>interp, name</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_GetParent</B>(<I>interp</I>)<BR>
<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<BR>
<B>Tcl_GetMaster</B>(<I>interp</I>)<BR>
int<BR>
<B>Tcl_GetInterpPath</B>(<I>interp, childInterp</I>)<BR>
int<BR>
<B>Tcl_CreateAlias</B>(<I>childInterp, childCmd, targetInterp, targetCmd,<BR>
<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>argc, argv</I>)<BR>
int<BR>
<B>Tcl_CreateAliasObj</B>(<I>childInterp, childCmd, targetInterp, targetCmd,<BR>
<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>objc, objv</I>)<BR>
int<BR>
<B>Tcl_GetAlias</B>(<I>interp, childCmd, targetInterpPtr, targetCmdPtr,<BR>
<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>argcPtr, argvPtr</I>)<BR>
int<BR>
<B>Tcl_GetAliasObj</B>(<I>interp, childCmd, targetInterpPtr, targetCmdPtr,<BR>
<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>objcPtr, objvPtr</I>)<BR>
int<BR>
<B>Tcl_ExposeCommand</B>(<I>interp, hiddenCmdName, cmdName</I>)<BR>
int<BR>
<B>Tcl_HideCommand</B>(<I>interp, cmdName, hiddenCmdName</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in)<DD>
Interpreter in which to execute the specified command.
<P><DT>const char <B>*name</B> (in)<DD>
Name of child interpreter to create or manipulate.
<P><DT>int <B>isSafe</B> (in)<DD>
If non-zero, a
&ldquo;safe&rdquo;
child that is suitable for running untrusted code
is created, otherwise a trusted child is created.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*childInterp</B> (in)<DD>
Interpreter to use for creating the source command for an alias (see
below).
<P><DT>const char <B>*childCmd</B> (in)<DD>
Name of source command for alias.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*targetInterp</B> (in)<DD>
Interpreter that contains the target command for an alias.
<P><DT>const char <B>*targetCmd</B> (in)<DD>
Name of target command for alias in <I>targetInterp</I>.
<P><DT>int <B><A HREF="../TclCmd/tclvars.htm">argc</A></B> (in)<DD>
Count of additional arguments to pass to the alias command.
<P><DT>const char *const <B>*argv</B> (in)<DD>
Vector of strings, the additional arguments to pass to the alias command.
This storage is owned by the caller.
<P><DT>int <B>objc</B> (in)<DD>
Count of additional value arguments to pass to the aliased command.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>**objv</B> (in)<DD>
Vector of <A HREF="../TclLib/Object.htm">Tcl_Obj</A> structures, the additional value arguments to pass to
the aliased command.
This storage is owned by the caller.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>**targetInterpPtr</B> (in)<DD>
Pointer to location to store the address of the interpreter where a target
command is defined for an alias.
<P><DT>const char <B>**targetCmdPtr</B> (out)<DD>
Pointer to location to store the address of the name of the target command
for an alias.
<P><DT>int <B>*argcPtr</B> (out)<DD>
Pointer to location to store count of additional arguments to be passed to
the alias. The location is in storage owned by the caller.
<P><DT>const char <B>***argvPtr</B> (out)<DD>
Pointer to location to store a vector of strings, the additional arguments
to pass to an alias. The location is in storage owned by the caller, the
vector of strings is owned by the called function.
<P><DT>int <B>*objcPtr</B> (out)<DD>
Pointer to location to store count of additional value arguments to be
passed to the alias. The location is in storage owned by the caller.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>***objvPtr</B> (out)<DD>
Pointer to location to store a vector of <A HREF="../TclLib/Object.htm">Tcl_Obj</A> structures, the additional
arguments to pass to an alias command. The location is in storage
owned by the caller, the vector of <A HREF="../TclLib/Object.htm">Tcl_Obj</A> structures is owned by the
called function.
<P><DT>const char <B>*cmdName</B> (in)<DD>
Name of an exposed command to hide or create.
<P><DT>const char <B>*hiddenCmdName</B> (in)<DD>
Name under which a hidden command is stored and with which it can be
exposed or invoked.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These procedures are intended for access to the multiple interpreter
facility from inside C programs. They enable managing multiple interpreters
in a hierarchical relationship, and the management of aliases, commands
that when invoked in one interpreter execute a command in another
interpreter. The return value for those procedures that return an <B>int</B>
is either <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B> or <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B>. If <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> is returned
then the interpreter's result contains an error message.
<P>
<B>Tcl_CreateSlave</B> creates a new interpreter as a child of <I>interp</I>.
It also creates a child command named <I>childName</I> in <I>interp</I> which
allows <I>interp</I> to manipulate the new child.
If <I>isSafe</I> is zero, the command creates a trusted child in which Tcl
code has access to all the Tcl commands.
If it is <B>1</B>, the command creates a
&ldquo;safe&rdquo;
child in which Tcl code has access only to set of Tcl commands defined as
&ldquo;Safe Tcl&rdquo;;
see the manual entry for the Tcl <B><A HREF="../TclCmd/interp.htm">interp</A></B> command for details.
If the creation of the new child interpreter failed, <B>NULL</B> is returned.
<P>
<B>Tcl_CreateChild</B> is a synonym for <B>Tcl_CreateSlave</B>.
<P>
<B>Tcl_IsSafe</B> returns <B>1</B> if <I>interp</I> is
&ldquo;safe&rdquo;
(was created with the <B>TCL_SAFE_INTERPRETER</B> flag specified),
<B>0</B> otherwise.
<P>
<B>Tcl_MakeSafe</B> marks <I>interp</I> as
&ldquo;safe&rdquo;,
so that future
calls to <B>Tcl_IsSafe</B> will return 1.  It also removes all known
potentially-unsafe core functionality (both commands and variables)
from <I>interp</I>.  However, it cannot know what parts of an extension
or application are safe and does not make any attempt to remove those
parts, so safety is not guaranteed after calling <B>Tcl_MakeSafe</B>.
Callers will want to take care with their use of <B>Tcl_MakeSafe</B>
to avoid false claims of safety.  For many situations, <B>Tcl_CreateSlave</B>
may be a better choice, since it creates interpreters in a known-safe state.
<P>
<B>Tcl_GetSlave</B> returns a pointer to a child interpreter of
<I>interp</I>. The child interpreter is identified by <I>childName</I>.
If no such child interpreter exists, <B>NULL</B> is returned.
<P>
<B>Tcl_GetChild</B> is a synonym for <B>Tcl_GetSlave</B>.
<P>
<B>Tcl_GetMaster</B> returns a pointer to the master interpreter of
<I>interp</I>. If <I>interp</I> has no master (it is a
top-level interpreter) then <B>NULL</B> is returned.
<P>
<B>Tcl_GetParent</B> is a synonym for <B>Tcl_GetMaster</B>.
<P>
<B>Tcl_GetInterpPath</B> stores in the result of <I>interp</I>
the relative path between <I>interp</I> and <I>childInterp</I>;
<I>childInterp</I> must be a child of <I>interp</I>. If the computation
of the relative path succeeds, <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B> is returned, else
<B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> is returned and an error message is stored as the
result of <I>interp</I>.
<P>
<B>Tcl_CreateAlias</B> creates a command named <I>childCmd</I> in
<I>childInterp</I> that when invoked, will cause the command <I>targetCmd</I>
to be invoked in <I>targetInterp</I>. The arguments specified by the strings
contained in <I>argv</I> are always prepended to any arguments supplied in the
invocation of <I>childCmd</I> and passed to <I>targetCmd</I>.
This operation returns <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B> if it succeeds, or <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> if
it fails; in that case, an error message is left in the value result
of <I>childInterp</I>.
Note that there are no restrictions on the ancestry relationship (as
created by <B>Tcl_CreateSlave</B>) between <I>childInterp</I> and
<I>targetInterp</I>. Any two interpreters can be used, without any
restrictions on how they are related.
<P>
<B>Tcl_CreateAliasObj</B> is similar to <B>Tcl_CreateAlias</B> except
that it takes a vector of values to pass as additional arguments instead
of a vector of strings.
<P>
<B>Tcl_GetAlias</B> returns information about an alias <I>aliasName</I>
in <I>interp</I>. Any of the result fields can be <B>NULL</B>, in
which case the corresponding datum is not returned. If a result field is
non-<B>NULL</B>, the address indicated is set to the corresponding datum.
For example, if <I>targetNamePtr</I> is non-<B>NULL</B> it is set to a
pointer to the string containing the name of the target command.
<P>
<B>Tcl_GetAliasObj</B> is similar to <B>Tcl_GetAlias</B> except that it
returns a pointer to a vector of <A HREF="../TclLib/Object.htm">Tcl_Obj</A> structures instead of a vector of
strings.
<P>
<B>Tcl_ExposeCommand</B> moves the command named <I>hiddenCmdName</I> from
the set of hidden commands to the set of exposed commands, putting
it under the name
<I>cmdName</I>.
<I>HiddenCmdName</I> must be the name of an existing hidden
command, or the operation will return <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and
leave an error message as the result of <I>interp</I>.
If an exposed command named <I>cmdName</I> already exists,
the operation returns <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and leaves an error message as
the result of <I>interp</I>.
If the operation succeeds, it returns <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B>.
After executing this command, attempts to use <I>cmdName</I> in any
script evaluation mechanism will again succeed.
<P>
<B>Tcl_HideCommand</B> moves the command named <I>cmdName</I> from the set of
exposed commands to the set of hidden commands, under the name
<I>hiddenCmdName</I>.
<I>CmdName</I> must be the name of an existing exposed
command, or the operation will return <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and leave an error
message as the result of <I>interp</I>.
Currently both <I>cmdName</I> and <I>hiddenCmdName</I> must not contain
namespace qualifiers, or the operation will return <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and
leave an error message as the result of <I>interp</I>.
The <I>CmdName</I> will be looked up in the global namespace, and not
relative to the current namespace, even if the current namespace is not the
global one.
If a hidden command whose name is <I>hiddenCmdName</I> already
exists, the operation also returns <B><A HREF="../TclCmd/catch.htm">TCL_ERROR</A></B> and an error
message is left as the result of <I>interp</I>.
If the operation succeeds, it returns <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B>.
After executing this command, attempts to use <I>cmdName</I> in
any script evaluation mechanism will fail.
<P>
For a description of the Tcl interface to multiple interpreters, see
<I>interp(n)</I>.
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/interp.htm">interp</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#alias">alias</A>, <A href="../Keywords/C.htm#command">command</A>, <A href="../Keywords/E.htm#exposed commands">exposed commands</A>, <A href="../Keywords/H.htm#hidden commands">hidden commands</A>, <A href="../Keywords/I.htm#interpreter">interpreter</A>, <A href="../Keywords/I.htm#invoke">invoke</A>, <A href="../Keywords/P.htm#parent">parent</A>, <A href="../Keywords/C.htm#child">child</A>
<div class="copy">Copyright &copy; 1995-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
